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To3 MTB Distribution 
From’ T. Casey 
Date? 15 December 1975 


Subjects List Command Changes for New Storage System 


This MTB describes, and explains the reasons for, tne changes 
that wil! nave to be made to the tist command before the nen 
Storage System is instafied. It is written in the form of a 
notice to users of a change that nas already been made. 


Introduction 


Severai of tne items printed by the list command are kept in the 
Volume Table of Contents (VTOC) rather than In the directory, in 
the new Storage System. They aret date_time_modifled (dta), 
date_time_used (dtu), and records used. 


The V¥TOC entry (VTOCE) for each segment (or directory) In a 
directory is accessed individually, via a disk I/0 operation. 
(Directory entriess on tne other nand, are held in the pases of a 
directory» and one page fault could bring into core all of the 
entries in a smati directory.) It Is therefore more costiy and 
tlme-consuming (in terms of real elapsed time) to access both the 
directory entries and the VTOCEs of all entries in a alrectory, 
than it is to access only the directory entries. 


Timing tests on the NSS system on the development machine, 
executing the command “list -total™ in the directory >Idd>include 
(830 entries) give the following results (all flgures are times, 
in seconds) 


Elapsed Real CPU Virtual CPU 
no VTOc I/0 1.5 1.2 0-7 
vVToc 170 | 18.0 729 5.8 


Therefore, the tist command has been modified so thats oby 
defautt, it willl print only those items that are kept in the 
directorye It does» however, have the abllity to tist items from 
the VTOC>s when the user so specifies. The changes inciude the 
abilaty to print (and sort on) date _timelentry_modified (dtem) as 
an aiternative to dtm, and tength (in records) computed from the 
bitcount as an alternative to records used. 


The next section discusses the relationshlops between those date 
and tength items whose treatment by the tist commana has been 
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changedy and it shows why the new items are acceptable (and even 
preferable in some cases) substitutes for the old onese The 
final section describes the Interface changes to the list 
command. 


Dates and Lengths 


Tne bitcount indicates the position of the tast bit of meaningful 
information in a segment. (It has a daifferent meaning for 
directories. That will be discussed later.) The tast bit falts 
somewhere within the last page of the segment. The number of the 
last page (counting from 1) is the current length of the segment. 
The current tengtn can be computed from the bitcount by dividing 
the latter by (36*16924) and adding 1 if there Is a remainder. 
Tne current iength is malntained automatically by the storage 
Systeme (It is set fo the number of the tast page contalning any 
non-zero bits.) Tne bitcount is maintained by the command 
system. It is set by any user-ring procedure that changes the 
position of the tast meaningful bit in the segment. (The 
adjust_bit_count and set_bdbit_count commands attow the user to set 
it correctiys, or to any arbitrary vaiue, respectively.) Most 
instatied commands set the bitcount of any Segment that they 
modify. Users should make certain that afl orlvately-maintained 
commands and subroutines do the same. 


It should be noted tnat the above relatlonshlp between bltcount 
and current tength does not hotd if? 1) fhe bitcount is set 
incorrecttly$ or 2) the last page of meaningful informatlon is all 
zeros (a very rare case). 


The records used of a segment will equal fhe current tengths 
except when one or amore of the pages of the segment contaln all 
zeros (a rare case). Pages of zeros are not stored on disk, or 
charged to quota, or counted in the records used figure. The 
fist ana status commanas both print records usede (The status 
command also prints current tength, but onty when it is different 
from records used.) The records used flgure Is malntalned 
automatically by the storage system. 


Whenever the directory entry for an object in the storage system 
ils modified, tne dtem is updated to the current date_time. 
Setting the bitcount invoives modificatlon of the directory 
entry, and therefore forces dtem to be updated. 


The utm ana atu figures are set at the time a segment is 
deactivated, and they are updated to the current time whenever 
they are accessed while a segment remains activee On a very 
lightly toaded system, a segment can remaln active for hours, or 
even untli shutdown, causing the dtm and dtu figures to have a 
much tater vatue than fhe user would expect. 


Thus, dtem can be more accurate than dtm as an indicator of the 
time of tast modification. (It must be kept in mind, nowever, 
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that dtem is aiso updated by changes fo other user-settable 
atfributes, such ast acl, namess ring bracketSs safety switchs 
copy switch, max tengths entry bounds, etce? 


By defaults the iist command will print names, mode, and tength 
computed from bifcount. This involves no VTOC I/0. Also, the 
date_time_modlfied (dtm) argument will now cause dtem to be used 
(for sorting or printing), while a new argument causes the dtm 
from the VTOC to be used (see next section). For those segments 
whose bitcounts are ({correctiy) set whenevar they are modifled, 
the output orodauced by tne !Iist command using computed iength and 
dtem wiil be identical to that produced using records used and 
dtm, except that the time of modification wili be exact, rather 
than being a function of now quickiy tne modified segment gets 
deactivated. 


A zero in the tength column will usuatiy indicate a segment whose 
bifcount has not been correctiy set. Since many commands fait 
when operating on a segment whose ditcount is (incorrectly) set 
to zero, it is useful to be abie to detect such cases Dy a glance 
at tist command output. 


When arguments that force VTOC I[/0 are given, accessing of fhe 
VTOCEs is postponed as long as possible. Entries are eliminated 
on the basis of entry types starnames, and the -first N argument 
(except when sorting by a VIOC item is also specified), before 
the VTOCEs of the setected entries are accessed. For this 
reason, use of -first N Is recommenced over QUITIing,s, as a means 
of tisting oniy the first few entries In a farge dlrectory. 


Since it is possible to specify sorting on and orinting of items 
separately, if Is now possible to specify these two functions 
inconsistent iy. Doing so will rasuit in an error message and no 
other output. Consistency restrictions are given in the’ confrol 
argument and sort key descriptions in the next section. These 
restrictions can be summarizea as follows: tne ftist command can 
operate on onty one of the two size figures, and on oniy one of 
the two modification datese Any combination of arguments” that 
specifies sorting on one item while printing the otner item, 
within eitner pairs is Inconsistent and wll! be rejected, 


List Command Interface Changes 


Three new control arguments have been added, and one has been 
eliminated» The new ones are? 


“lengtinsg In print current tength comouted from bifcount. 
This argument is Inconsistent with -record; 
only one of the two nay be given. This 
argument is the tess expensive of the fwo, 
ana is the default. 
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-date_time_entry_modified 
-dtem print the date_time_entry_modified. Thls 
| argument is inconsistent with 
-date_time_contents_modifled$; only one of the 
two may be given. This argument is the less 
expensive of the two. 


-date_time_contents_modified 


-dtcm print the. date_time_contents_modl fied 
(formerly called date_time_modified or dtm). 
This argument Is InconsIistent with 


-date_time_entry_modified; only one of the 
two may be given. This argument is the more 
expensive of the two. 


The -date_time_modified {(-dtm) argument is now obsolete, but If 
will be accepted as a Synonym for -dtem. The reason for this Is 
to save users from making unintentional and expensive VTOC 
references, by typing the more commoniyeused of the two date 
arguments by force of habdlt. 


The -record control argument description Ils changed to read? 


“record, “rec print the records used. This argument Is 
Inconsistent wlth -length$; only one of the 
two may be given. This argument Is the more 
expensive of the tno. 


Three new sort Keys nave been added, and one has been eliminated. 
Tne new ones are’ 


fength. in sort by length computed from bitcount. This 
argument is inconsistent with the -record 
control argument. 


date_time_entry_modified 
dtem sort by date_time_entry_modi fied. This 
argument Is Inconsistent with the -dtcm 
argumente If the -dtem argument Is given, and 
no sort key control argument foliows -sort, 
then this argument is Inmptied as the default 
sort keye 


date_time_contents_modified 

dtem Sort by date_time_contents_modifled. This 
argument is Inconsistent with the -dtem 
control argument. If -dtcm is given and no 
sort key argument follows -sort, then thls 
argument is implied as the default sort key. 


The date_time_modified (dtm) sort key 1s obsolete, but it will be 
accepfed aS a synonym for dateme 
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The description of the record sort key is changed to read? 


record, rec sort by records used. This argument Is 
inconsistent with the -iengtn control 
argument. If this argument Is givens, and the 
defauit columns have not been overridden by 
the -brief or -name control arguments, then 
the -record argument is implled by this 
argumante 


Since the tength is computed from the bitcount, and directory 
bitcounts are never meaningful as tength Indicators (when 
nonzero, they are interpreted as msf component counts)», onty the 
mode and names columns are printed for directorles, by default. 
The records column is printed for directorles oniy when the 
“record control argument is givens ao 


Since The -record control! argument must now be used to specify 
that records used from the VTOC, rather than tength computed from 
bitcounts is to be printed, it wll! no tonger have the effect of 
overriding the column defaults. For consistency, the -mode 
argument witi also no tonger nave the effect of overriding the 
column defaults. NOW, onty the -orief ana ~-name control 
arguments will have that effect. 


